Defines a function the Scrap Manager calls to obtain promised scrap data. Your promise-keeper function provides scrap data for a specified flavor.

typedef OSStatus(* ScrapPromiseKeeperProcPtr) (
    ScrapRef scrap, 
    ScrapFlavorType flavorType, 
    void *userData
);

You would declare your function like this if you were to name it MyScrapPromiseKeeperCallback:

OSStatus MyScrapPromiseKeeperCallback (
    ScrapRef scrap, 
    ScrapFlavorType flavorType, 
    void *userData
);

Parameter descriptions

scrap

A reference to the scrap to which to supply the promised flavor data.

flavorType

The flavor type to supply the promised data for. Some scrap flavor types are described in “Scrap Flavor Type Constants”.

userData

An untyped pointer to a buffer, local variable, or other storage location, created and disposed of by your application, and supplied to the Scrap Manager by a previous call to SetScrapPromiseKeeper. For example, this parameter might refer to a pointer or handle to some private scrap data which your promise-keeper function uses in fabricating one or more promised flavors.

This parameter may have a value of NULL.

function result

A result code.

DISCUSSION

To provide a pointer to your promise-keeper function, you create a universal procedure pointer (UPP) of type ScrapPromiseKeeperUPP, using the function NewScrapPromiseKeeperUPP. You can do so with code like the following:

ScrapPromiseKeeperUPP MyPromiseKeeperUPP;

MyPromiseKeeperUPP = NewScrapPromiseKeeperUPP (&MyPromiseKeeperCallback);

You can then associate the UPP with a scrap by passing MyPromiseKeeperUPP as a parameter to the SetScrapPromiseKeeper function.

If a promised flavor is requested through GetScrapFlavorData or GetScrapFlavorSize, the Scrap Manager calls the application's ScrapPromiseKeeperProcPtr function. The scrap promise-keeper function should call PutScrapFlavor as appropriate to fulfill its promises. Failure to do so (including returning an error or simply neglecting to keep a promise for a flavor) will result in errors being returned to corresponding callers of GetScrapFlavorData or GetScrapFlavorSize.

Under Mac OS X, the scrap promise-keeper function can be called during any call to GetScrapFlavorData or GetScrapFlavorSize. Under Mac OS 8 and 9, the Carbon Scrap Manager still must support (non-Carbon) callers of GetScrap, which does not know about promised flavors. What the Carbon Scrap Manager must do as a result is to make sure all promises have been kept when the application is suspended.

It's OK to keep a promise without ever receiving a call to a scrap promise-keeper function. It would be bad for a scrap promise-keeper function to call WaitNextEvent or any similar function because the promise-keeper might be running at suspend event time, and this sort of thing tends to make Process Manager very cross.

If you wish to call your promise-keeper function directly, you can use the InvokeScrapPromiseKeeperUPP function.

After you are finished with a promise-keeper function, and have removed it by passing NULL to the SetScrapPromiseKeeper function, you can dispose of the UPP with theDisposeScrapPromiseKeeperUPP function. However, don’t dispose of the UPP if any other scrap uses it or if you plan to use it again.

© 2000 Apple Computer, Inc. (Last Updated 7/17/2000)